home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / u_man / cat3 / Tcl / setvar.z / setvar
Encoding:
Text File  |  2002-10-03  |  9.7 KB  |  199 lines
  1.  
  2.  
  3.  
  4. TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333TTTTccccllll))))                                              TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333TTTTccccllll))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tcl_SetVar, Tcl_SetVar2, Tcl_GetVar, Tcl_GetVar2, Tcl_UnsetVar,
  10.      Tcl_UnsetVar2 - manipulate Tcl variables
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>>
  14.  
  15.      char *
  16.      TTTTccccllll____SSSSeeeettttVVVVaaaarrrr(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _n_e_w_V_a_l_u_e, _f_l_a_g_s)
  17.  
  18.      char *
  19.      TTTTccccllll____SSSSeeeettttVVVVaaaarrrr2222(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _n_e_w_V_a_l_u_e, _f_l_a_g_s)
  20.  
  21.      char *
  22.      TTTTccccllll____GGGGeeeettttVVVVaaaarrrr(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _f_l_a_g_s)
  23.  
  24.      char *
  25.      TTTTccccllll____GGGGeeeettttVVVVaaaarrrr2222(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _f_l_a_g_s)
  26.  
  27.      int
  28.      TTTTccccllll____UUUUnnnnsssseeeettttVVVVaaaarrrr(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _f_l_a_g_s)
  29.  
  30.      int
  31.      TTTTccccllll____UUUUnnnnsssseeeettttVVVVaaaarrrr2222(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _f_l_a_g_s)
  32.  
  33. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  34.      Tcl_Interp   *_i_n_t_e_r_p     (in)      Interpreter containing variable.
  35.  
  36.      char         *_v_a_r_N_a_m_e    (in)      Name of variable.  May refer to a
  37.                                         scalar variable or an element of an
  38.                                         array variable.  If the name          |
  39.                                         references an element of an array,    |
  40.                                         then it must be in writable memory:   |
  41.                                         Tcl will make temporary modifications |
  42.                                         to it while looking up the name.
  43.  
  44.      char         *_n_e_w_V_a_l_u_e   (in)      New value for variable.
  45.  
  46.      int          _f_l_a_g_s       (in)      OR-ed combination of bits providing
  47.                                         additional information for operation.
  48.                                         See below for valid values.
  49.  
  50.      char         *_n_a_m_e_1      (in)      Name of scalar variable, or name of
  51.                                         array variable if _n_a_m_e_2 is non-NULL.
  52.  
  53.      char         *_n_a_m_e_2      (in)      If non-NULL, gives name of element
  54.                                         within array and _n_a_m_e_1 must refer to
  55.                                         an array variable.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333TTTTccccllll))))                                              TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333TTTTccccllll))))
  71.  
  72.  
  73.  
  74. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  75.      These procedures may be used to create, modify, read, and delete Tcl
  76.      variables from C code.  TTTTccccllll____SSSSeeeettttVVVVaaaarrrr and TTTTccccllll____SSSSeeeettttVVVVaaaarrrr2222 will create a new
  77.      variable or modify an existing one.  Both of these procedures set the
  78.      given variable to the value given by _n_e_w_V_a_l_u_e, and they return a pointer
  79.      to a copy of the variable's new value, which is stored in Tcl's variable
  80.      structure.  Tcl keeps a private copy of the variable's value, so the
  81.      caller may change _n_e_w_V_a_l_u_e after these procedures return without
  82.      affecting the value of the variable.  If an error occurs in setting the
  83.      variable (e.g. an array variable is referenced without giving an index
  84.      into the array), then NULL is returned.
  85.  
  86.      The name of the variable may be specified in either of two ways.  If
  87.      TTTTccccllll____SSSSeeeettttVVVVaaaarrrr is called, the variable name is given as a single string,
  88.      _v_a_r_N_a_m_e.  If _v_a_r_N_a_m_e contains an open parenthesis and ends with a close
  89.      parenthesis, then the value between the parentheses is treated as an
  90.      index (which can have any string value) and the characters before the
  91.      first open parenthesis are treated as the name of an array variable.  If
  92.      _v_a_r_N_a_m_e doesn't have parentheses as described above, then the entire
  93.      string is treated as the name of a scalar variable.  If TTTTccccllll____SSSSeeeettttVVVVaaaarrrr2222 is
  94.      called, then the array name and index have been separated by the caller
  95.      into two separate strings, _n_a_m_e_1 and _n_a_m_e_2 respectively;  if _n_a_m_e_2 is
  96.      zero it means that a scalar variable is being referenced.
  97.  
  98.      The _f_l_a_g_s argument may be used to specify any of several options to the
  99.      procedures.  It consists of an OR-ed combination of any of the following
  100.      bits:
  101.  
  102.      TCL_GLOBAL_ONLY
  103.           Under normal circumstances the procedures look up variables at the
  104.           current level of procedure call for _i_n_t_e_r_p, or at global level if
  105.           there is no call active.  However, if this bit is set in _f_l_a_g_s then
  106.           the variable is looked up at global level even if there is a
  107.           procedure call active.
  108.  
  109.      TCL_LEAVE_ERR_MSG
  110.           If an error is returned and this bit is set in _f_l_a_g_s, then an error
  111.           message will be left in _i_n_t_e_r_p->_r_e_s_u_l_t.  If this flag bit isn't set
  112.           then no error message is left (_i_n_t_e_r_p->_r_e_s_u_l_t will not be modified).
  113.  
  114.      TCL_APPEND_VALUE
  115.           If this bit is set then _n_e_w_V_a_l_u_e is appended to the current value,
  116.           instead of replacing it.  If the variable is currently undefined,
  117.           then this bit is ignored.
  118.  
  119.      TCL_LIST_ELEMENT
  120.           If this bit is set, then _n_e_w_V_a_l_u_e is converted to a valid Tcl list
  121.           element before setting (or appending to) the variable.  A separator
  122.           space is appended before the new list element unless the list       |
  123.           element is going to be the first element in a list or sublist (i.e. |
  124.           the variable's current value is empty, or contains the single       |
  125.           character ``{'', or ends in `` }'').
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333TTTTccccllll))))                                              TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333TTTTccccllll))))
  137.  
  138.  
  139.  
  140.      TTTTccccllll____GGGGeeeettttVVVVaaaarrrr and TTTTccccllll____GGGGeeeettttVVVVaaaarrrr2222 return the current value of a variable.  The
  141.      arguments to these procedures are treated in the same way as the
  142.      arguments to TTTTccccllll____SSSSeeeettttVVVVaaaarrrr and TTTTccccllll____SSSSeeeettttVVVVaaaarrrr2222.  Under normal circumstances, the
  143.      return value is a pointer to the variable's value (which is stored in
  144.      Tcl's variable structure and will not change before the next call to
  145.      TTTTccccllll____SSSSeeeettttVVVVaaaarrrr or TTTTccccllll____SSSSeeeettttVVVVaaaarrrr2222).  The only bits of _f_l_a_g_s that are used are
  146.      TCL_GLOBAL_ONLY and TCL_LEAVE_ERR_MSG, both of which have the same
  147.      meaning as for TTTTccccllll____SSSSeeeettttVVVVaaaarrrr.  If an error occurs in reading the variable
  148.      (e.g. the variable doesn't exist or an array element is specified for a
  149.      scalar variable), then NULL is returned.
  150.  
  151.      TTTTccccllll____UUUUnnnnsssseeeettttVVVVaaaarrrr and TTTTccccllll____UUUUnnnnsssseeeettttVVVVaaaarrrr2222 may be used to remove a variable, so that
  152.      future calls to TTTTccccllll____GGGGeeeettttVVVVaaaarrrr or TTTTccccllll____GGGGeeeettttVVVVaaaarrrr2222 for the variable will return an
  153.      error.  The arguments to these procedures are treated in the same way as
  154.      the arguments to TTTTccccllll____GGGGeeeettttVVVVaaaarrrr and TTTTccccllll____GGGGeeeettttVVVVaaaarrrr2222.  If the variable is         |
  155.      successfully removed then TCL_OK is returned.  If the variable cannot be |
  156.      removed because it doesn't exist then TCL_ERROR is returned.  If an array
  157.      element is specified, the given element is removed but the array remains.
  158.      If an array name is specified without an index, then the entire array is
  159.      removed.
  160.  
  161.  
  162. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  163.      Tcl_TraceVar
  164.  
  165.  
  166. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  167.      array, interpreter, scalar, set, unset, variable
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.